فرمت توزیع Wheel: ایجاد بسته های باینری برای پایتون

اکوسیستم پایتون به شدت به مدیریت کارآمد بسته ها متکی است. یکی از ارکان اصلی این اکوسیستم، فرمت توزیع Wheel است که اغلب با پسوند .whl مشخص می شود. این راهنما به بررسی پیچیدگی های فرمت Wheel، مزایای آن و نحوه ایجاد بسته های باینری برای پایتون می پردازد، که برای توسعه دهندگان در سراسر جهان که هدفشان توزیع نرم افزار روان و قابل اعتماد است، ارائه شده است.

فرمت Wheel چیست؟

فرمت Wheel یک فرمت بسته بندی شده برای پایتون است. این فرمت طوری طراحی شده که راحت تر از توزیع های سورس (sdist) نصب شود. به عنوان جایگزینی برای فرمت قدیمی تر egg عمل می کند و چندین مورد از کاستی های آن را برطرف می کند. اساساً، این یک آرشیو ZIP با یک ساختار و فراداده خاص است که به pip و سایر ابزارهای نصب اجازه می دهد تا به سرعت بسته را بدون نیاز به ساخت آن از منبع نصب کنند.

ویژگی های کلیدی Wheel

• استقلال از پلتفرم (در صورت لزوم): Wheel ها را می توان برای پلتفرم ها و معماری های خاص (به عنوان مثال، ویندوز 64 بیتی، لینوکس x86_64) ساخت یا مستقل از پلتفرم (پایتون خالص) باشند. این امکان ایجاد باینری های بهینه شده برای سیستم عامل های مختلف را فراهم می کند.
• نصب آسان: فرمت Wheel شامل توزیع های از پیش ساخته شده است که نیاز به کامپایل کد در طول نصب را به حداقل می رساند. این امر به طور قابل توجهی سرعت نصب را افزایش می دهد، به ویژه برای بسته هایی که دارای افزونه های C یا سایر اجزای کامپایل شده هستند.
• شمول فراداده: Wheel ها شامل تمام فراداده های لازم در مورد بسته، از جمله وابستگی ها، اطلاعات نسخه و نقاط ورودی هستند. این فراداده برای مدیران بسته مانند pip برای مدیریت وابستگی ها و نصب صحیح بسته بسیار مهم است.
• نصب اتمی: pip بسته ها را از Wheel ها به صورت اتمی نصب می کند. این بدان معنی است که نصب یا با موفقیت کامل می شود یا به طور کامل برمی گردد و از نصب جزئی بسته ها جلوگیری می کند، که می تواند منجر به ناسازگاری شود.
• تکرارپذیری: Wheel ها با ارائه یک مصنوع ساخت سازگار که می تواند در چندین محیط بدون نیاز به کامپایل مجدد نصب شود (با فرض مطابقت پلتفرم هدف)، تکرارپذیری را افزایش می دهند.

چرا از Wheel ها استفاده کنیم؟

انتخاب Wheel ها به جای توزیع های سورس، مزایای بی شماری را ارائه می دهد و فرآیند نصب و استقرار بسته را ساده می کند. در اینجا خلاصه ای از مزایای کلیدی آورده شده است:

زمان نصب سریعتر

یکی از مهمترین مزایای Wheel ها سرعت آنهاست. Wheel ها با ارائه توزیع های از پیش ساخته شده، نیاز به کامپایل کد در طول نصب را از بین می برند. این امر به ویژه برای بسته هایی با افزونه های کامپایل شده که به زبان C، C++ یا سایر زبان ها نوشته شده اند، مفید است. تصور کنید که یک کتابخانه علمی پیچیده را مستقر می کنید. استفاده از Wheel به طور چشمگیری زمان راه اندازی را در دستگاه های کاربر نهایی کاهش می دهد.

مثال: نصب numpy از منبع می تواند چندین دقیقه طول بکشد، به خصوص در سخت افزارهای قدیمی تر. نصب از Wheel معمولاً چند ثانیه طول می کشد.

کاهش وابستگی به ابزارهای ساخت

نصب بسته ها از منبع اغلب مستلزم آن است که کاربران ابزارهای ساخت لازم (کامپایلرها، هدرها و غیره) را روی سیستم خود نصب کنند. این می تواند یک مانع برای ورود باشد، به ویژه برای کاربرانی که با توسعه نرم افزار آشنا نیستند. Wheel ها این وابستگی را حذف می کنند و نصب را ساده تر و در دسترس تر می کنند.

مثال: یک دانشمند داده در یک آزمایشگاه تحقیقاتی ممکن است کامپایلرهای لازم برای ساخت یک بسته از منبع را نداشته باشد. Wheel به آنها اجازه می دهد تا بسته را مستقیماً بدون نیاز به پیکربندی محیط خود نصب کنند.

بهبود قابلیت اطمینان

Wheel ها با ارائه باینری های از پیش ساخته شده، اطمینان حاصل می کنند که بسته به شیوه ای سازگار در محیط های مختلف نصب می شود. این امر خطر خطاهای نصب به دلیل تغییرات در پیکربندی سیستم یا نسخه های ابزار ساخت را کاهش می دهد. این سازگاری برای برنامه هایی که نیاز به رفتار پایدار و قابل پیش بینی دارند، بسیار مهم است.

مثال: یک برنامه وب که در چندین سرور مستقر شده است، باید نسخه های بسته سازگار داشته باشد. استفاده از Wheel ها تضمین می کند که باینری های یکسانی روی هر سرور نصب می شوند و خطر مشکلات استقرار را به حداقل می رساند.

افزایش امنیت

Wheel ها می توانند برای تأیید اصالت و یکپارچگی خود امضا شوند. این امر به جلوگیری از توزیع بسته های دستکاری شده توسط بازیگران مخرب کمک می کند. امضای بسته یک لایه امنیتی اضافی را فراهم می کند و اطمینان می دهد که کاربران در حال نصب نرم افزار قابل اعتماد هستند.

مثال: سازمان ها می توانند سیاست هایی را اجرا کنند که مستلزم آن است که قبل از استقرار در محیط های تولیدی، تمام بسته ها امضا شوند. این امر از حملات زنجیره تامین که در آن کد مخرب به بسته ها تزریق می شود، محافظت می کند.

ایجاد بسته های Wheel: راهنمای گام به گام

ایجاد بسته های Wheel یک فرآیند ساده است که شامل استفاده از بسته های setuptools و wheel می شود. در اینجا یک راهنمای مفصل آورده شده است:

1. تنظیم پروژه خود

ابتدا اطمینان حاصل کنید که پروژه شما به درستی ساختاربندی شده است. حداقل، شما به یک فایل setup.py و کد منبع بسته خود نیاز دارید.

مثال ساختار پروژه:

my_package/
 ├── my_module/
 │   ├── __init__.py
 │   └── my_function.py
 ├── setup.py
 └── README.md

2. فایل setup.py

فایل setup.py قلب پروژه شماست. این فایل حاوی فراداده در مورد بسته شما است و نحوه ساخت و نصب آن را تعریف می کند. در اینجا نمونه ای از فایل setup.py آورده شده است:

from setuptools import setup, find_packages

setup(
 name='my_package',
 version='0.1.0',
 description='A simple example package',
 long_description=open('README.md').read(),
 long_description_content_type='text/markdown',
 url='https://github.com/your_username/my_package',
 author='Your Name',
 author_email='your.email@example.com',
 license='MIT',
 packages=find_packages(),
 install_requires=['requests'],
 classifiers=[
 'Development Status :: 3 - Alpha',
 'Intended Audience :: Developers',
 'License :: OSI Approved :: MIT License',
 'Programming Language :: Python :: 3',
 'Programming Language :: Python :: 3.6',
 'Programming Language :: Python :: 3.7',
 'Programming Language :: Python :: 3.8',
 'Programming Language :: Python :: 3.9',
 ],
)

توضیح فیلدهای کلیدی:

• name: نام بسته شما. این نامی است که کاربران برای نصب بسته شما استفاده می کنند (به عنوان مثال، pip install my_package).
• version: شماره نسخه بسته شما. از نسخه بندی معنایی (SemVer) برای روش های نسخه بندی سازگار (به عنوان مثال، 0.1.0، 1.0.0، 2.5.1) پیروی کنید.
• description: توضیحات کوتاهی از بسته شما.
• long_description: توضیحات مفصلی از بسته شما. این اغلب از یک فایل README.md خوانده می شود.
• url: آدرس صفحه اصلی یا مخزن بسته شما.
• author: نام نویسنده بسته.
• author_email: آدرس ایمیل نویسنده بسته.
• license: مجوزی که بسته شما تحت آن توزیع می شود (به عنوان مثال، MIT، Apache 2.0، GPL).
• packages: لیستی از بسته هایی که در توزیع خود قرار می دهید. find_packages() به طور خودکار تمام بسته ها را در پروژه شما پیدا می کند.
• install_requires: لیستی از وابستگی هایی که بسته شما به آن نیاز دارد. pip به طور خودکار این وابستگی ها را هنگام نصب بسته شما نصب می کند.
• classifiers: فراداده ای که به کاربران کمک می کند بسته شما را در PyPI (فهرست بسته پایتون) پیدا کنند. این طبقه بندی ها وضعیت توسعه، مخاطبان مورد نظر، مجوز و نسخه های پشتیبانی شده پایتون را شرح می دهند.

3. نصب wheel

اگر بسته wheel را نصب نکرده اید، می توانید آن را با استفاده از pip نصب کنید:

pip install wheel

4. ساخت بسته Wheel

به دایرکتوری ریشه پروژه خود (جایی که setup.py قرار دارد) بروید و دستور زیر را اجرا کنید:

python setup.py bdist_wheel

این دستور یک دایرکتوری dist ایجاد می کند که حاوی بسته Wheel (فایل .whl) و یک توزیع سورس (فایل .tar.gz) است.

5. یافتن فایل Wheel

فایل Wheel تولید شده در دایرکتوری dist قرار خواهد گرفت. نام آن از فرمت package_name-version-pyXX-none-any.whl پیروی می کند، که در آن:

• package_name: نام بسته شما.
• version: شماره نسخه بسته شما.
• pyXX: نسخه پایتون که بسته با آن سازگار است (به عنوان مثال، py37 برای پایتون 3.7).
• none: نشان می دهد که بسته خاص پلتفرم نیست.
• any: نشان می دهد که بسته با هر معماری سازگار است.

برای Wheel های خاص پلتفرم، برچسب های none و any با شناسه های پلتفرم و معماری جایگزین می شوند (به عنوان مثال، win_amd64 برای ویندوز 64 بیتی).

6. تست بسته Wheel

قبل از توزیع بسته Wheel خود، ضروری است که آن را آزمایش کنید تا اطمینان حاصل شود که به درستی نصب می شود. می توانید این کار را با استفاده از pip انجام دهید:

pip install dist/my_package-0.1.0-py39-none-any.whl

dist/my_package-0.1.0-py39-none-any.whl را با مسیر واقعی فایل Wheel خود جایگزین کنید.

7. توزیع بسته Wheel خود

پس از ساخت و آزمایش بسته Wheel خود، می توانید آن را از طریق کانال های مختلف توزیع کنید:

• PyPI (فهرست بسته پایتون): رایج ترین راه برای توزیع بسته های پایتون. می توانید بسته Wheel خود را با استفاده از twine در PyPI آپلود کنید.
• فهرست بسته خصوصی: برای استفاده داخلی در یک سازمان، می توانید یک فهرست بسته خصوصی با استفاده از ابزارهایی مانند devpi یا Artifactory تنظیم کنید.
• توزیع مستقیم: همچنین می توانید بسته Wheel خود را مستقیماً از طریق ایمیل، اشتراک فایل یا سایر روش ها در اختیار کاربران قرار دهید.

مدیریت افزونه های C و Wheel های خاص پلتفرم

ایجاد Wheel های خاص پلتفرم، به ویژه آنهایی که حاوی افزونه های C هستند، به مراحل اضافی نیاز دارد. در اینجا یک نمای کلی از این فرآیند آورده شده است:

1. کامپایل افزونه های C

افزونه های C باید برای هر پلتفرم هدف کامپایل شوند. این معمولاً شامل استفاده از یک کامپایلر C (به عنوان مثال، GCC، MSVC) و ابزارهای ساخت خاص پلتفرم است.

مثال: در ویندوز، باید از کامپایلر Microsoft Visual C++ برای ساخت افزونه های C استفاده کنید. در لینوکس، معمولاً از GCC استفاده می کنید.

2. استفاده از cffi یا Cython

ابزارهایی مانند cffi و Cython می توانند فرآیند ایجاد افزونه های C را ساده کنند. cffi به شما امکان می دهد کد C را مستقیماً از پایتون بدون نوشتن کد C خود فراخوانی کنید، در حالی که Cython به شما امکان می دهد کد C مانند را بنویسید که به افزونه های C کامپایل می شود.

3. تعریف وابستگی های خاص پلتفرم

در فایل setup.py خود، می توانید وابستگی های خاص پلتفرم را با استفاده از پارامترهای setup_requires و install_requires تعریف کنید. این به شما امکان می دهد وابستگی های مختلفی را برای پلتفرم های مختلف مشخص کنید.

مثال:

from setuptools import setup, Extension
import platform

if platform.system() == 'Windows':
 extra_compile_args = ['/O2', '/EHsc']
else:
 extra_compile_args = ['-O3']

setup(
 name='my_package',
 version='0.1.0',
 ext_modules=[
 Extension(
 'my_package.my_extension',
 ['my_package/my_extension.c'],
 extra_compile_args=extra_compile_args,
 ),
 ],
)

4. ساخت Wheel های خاص پلتفرم

برای ساخت Wheel های خاص پلتفرم، باید از محیط ساخت مناسب برای هر پلتفرم هدف استفاده کنید. این ممکن است شامل استفاده از ماشین های مجازی یا فناوری های کانتینری مانند Docker باشد.

مثال: برای ساخت یک Wheel برای ویندوز 64 بیتی، باید فرآیند ساخت را روی یک سیستم ویندوز 64 بیتی با کامپایلر Microsoft Visual C++ نصب شده اجرا کنید.

بهترین شیوه ها برای ایجاد بسته Wheel

رعایت بهترین شیوه ها تضمین می کند که بسته های Wheel شما قابل اعتماد، قابل نگهداری و آسان برای استفاده هستند. در اینجا چند توصیه کلیدی آورده شده است:

1. استفاده از نسخه بندی معنایی (SemVer)

از نسخه بندی معنایی (SemVer) برای روش های نسخه بندی سازگار پیروی کنید. SemVer از یک شماره نسخه سه قسمتی (MAJOR.MINOR.PATCH) برای نشان دادن نوع تغییرات در هر نسخه استفاده می کند.

• MAJOR: نشان دهنده تغییرات API ناسازگار است.
• MINOR: نشان دهنده ویژگی های جدیدی است که با عقب سازگار هستند.
• PATCH: نشان دهنده رفع اشکالاتی است که با عقب سازگار هستند.

مثال: تغییر پارامترهای یک تابع به گونه ای که کد موجود را خراب کند، مستلزم افزایش نسخه اصلی است (به عنوان مثال، از 1.0.0 به 2.0.0). اضافه کردن یک تابع جدید بدون تغییر توابع موجود، مستلزم افزایش نسخه جزئی است (به عنوان مثال، از 1.0.0 به 1.1.0). رفع یک اشکال مستلزم افزایش نسخه پچ است (به عنوان مثال، از 1.0.0 به 1.0.1).

2. گنجاندن یک فایل README.md

یک فایل README.md را درج کنید که شرح مفصلی از بسته شما، از جمله دستورالعمل های نصب، نمونه های استفاده و دستورالعمل های مشارکت ارائه می دهد. این به کاربران کمک می کند تا نحوه استفاده از بسته شما را درک کنند و مشارکت را تشویق می کند.

3. نوشتن مستندات واضح و مختصر

مستندات واضح و مختصری را برای بسته خود بنویسید، از جمله مستندات API، آموزش ها و مثال ها. از ابزارهایی مانند Sphinx یا Read the Docs برای تولید مستندات از نظرات کد خود استفاده کنید.

4. استفاده از مجوز

مجوزی را برای بسته خود انتخاب کنید که به وضوح شرایطی را که تحت آن می توان آن را استفاده، اصلاح و توزیع کرد، تعریف می کند. مجوزهای رایج عبارتند از MIT، Apache 2.0 و GPL.

5. بسته خود را به طور کامل آزمایش کنید

بسته خود را با استفاده از ابزارهای تست خودکار مانند pytest یا unittest به طور کامل آزمایش کنید. تست های واحد، تست های یکپارچه سازی و تست های سرتاسر را بنویسید تا اطمینان حاصل شود که بسته شما به درستی در سناریوهای مختلف کار می کند.

6. استفاده از یکپارچه سازی مداوم (CI)

از ابزارهای یکپارچه سازی مداوم (CI) مانند GitHub Actions، GitLab CI یا Jenkins برای ساخت و آزمایش خودکار بسته خود هر زمان که تغییری در کد ایجاد می شود استفاده کنید. این کمک می کند تا اشکالات به زودی برطرف شوند و اطمینان حاصل شود که بسته شما همیشه در حالت کار است.

7. امضای بسته های خود

بسته های خود را برای تأیید اصالت و یکپارچگی آنها امضا کنید. این کمک می کند تا از توزیع بسته های دستکاری شده توسط بازیگران مخرب جلوگیری شود. از ابزارهایی مانند gpg یا keyring برای امضای بسته های خود استفاده کنید.

تکنیک های پیشرفته Wheel

برای موارد استفاده پیشرفته تر، این تکنیک ها را در نظر بگیرید:

1. استفاده از build

بسته build یک روش مدرن و استاندارد برای ساخت بسته های پایتون ارائه می دهد. این بسته از توزیع های Wheel و سورس پشتیبانی می کند و رابط کاربری ساده تری نسبت به setuptools ارائه می دهد.

pip install build
python -m build

2. نصب های قابل ویرایش

نصب های قابل ویرایش به شما امکان می دهند بسته را به گونه ای نصب کنید که مستقیماً به کد منبع پیوند داشته باشد. این برای توسعه مفید است، زیرا تغییرات در کد منبع بلافاصله در بسته نصب شده منعکس می شود بدون نیاز به نصب مجدد آن.

pip install -e .

3. سفارشی کردن فرآیند ساخت

می توانید فرآیند ساخت را با تعریف اسکریپت های ساخت سفارشی یا استفاده از سیستم های ساخت مانند Meson یا CMake سفارشی کنید. این به شما امکان می دهد سناریوهای ساخت پیچیده تری را مدیریت کنید، مانند ساخت افزونه های C با پرچم های کامپایلر خاص یا پیوند دادن به کتابخانه های خارجی.

4. استفاده از auditwheel

ابزار auditwheel برای ممیزی و تعمیر Wheel های لینوکس که حاوی کتابخانه های مشترک هستند استفاده می شود. این اطمینان حاصل می کند که Wheel شامل تمام وابستگی های لازم برای اجرا در طیف گسترده ای از توزیع های لینوکس است.

pip install auditwheel
auditwheel repair dist/my_package-0.1.0-py39-linux_x86_64.whl

نتیجه گیری

فرمت توزیع Wheel یک ابزار ضروری برای توسعه دهندگان پایتون است که هدفشان توزیع بسته کارآمد، قابل اعتماد و ایمن است. با پیروی از مراحلی که در این راهنما تشریح شده است و اتخاذ بهترین شیوه ها، می توانید بسته های Wheel ایجاد کنید که فرآیند نصب را ساده می کنند، وابستگی به ابزارهای ساخت را کاهش می دهند و تجربه کاربری کلی را بهبود می بخشند. چه در حال توزیع بسته ها در جامعه منبع باز باشید و چه در حال استقرار برنامه های کاربردی داخلی، درک و استفاده از فرمت Wheel یک مهارت ارزشمند برای هر توسعه دهنده پایتون است. با ادامه تکامل پایتون، پذیرش شیوه های بسته بندی مدرن مانند Wheel تضمین می کند که پروژه های شما برای مخاطبان جهانی قابل دسترسی و نگهداری باقی می مانند.

با پذیرش این شیوه ها، شما به یک اکوسیستم پایتون قوی تر و در دسترس تر در سراسر جهان کمک می کنید.